@rubytech/create-realagent 1.0.816 → 1.0.817

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent",
-  "version": "1.0.816",
+  "version": "1.0.817",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent": "./dist/index.js"

package/payload/platform/plugins/admin/skills/onboarding/SKILL.md

@@ -6,7 +6,7 @@ After completing each step, persist progress immediately by calling `onboarding-
 
 Every user selection and every document presentation in onboarding renders through `render-component` — never as markdown text, bullet lists, or inline chat content. Selections use `single-select` or `multi-select`; file content (SOUL, KNOWLEDGE, config) uses `document-editor`. Describing options in prose or pasting file content into a chat message bypasses the UI and the user's ability to review and edit before saving. Never use directional words ("above", "below") when referring to a rendered component — just name it or refer to "the browser", "the editor", etc. The `document-editor` component renders one file at a time — never call `render-component` with `document-editor` twice in the same turn. Present one file, wait for the user's approval or edit, then present the next.
 
-**Turn-completion contract (Task 879 §C).** Any onboarding turn that advances `currentStep` (via `onboarding-complete-step`) OR narrates a step transition with phrases like "Moving to step N", "Proceeding to step N", "Step N done" MUST end with one of: a `render-component` call surfacing the next step's UI, OR a `?`-terminated question. Bare prose statements like "Moving to step 9 — operator persona and profile bootstrap." with nothing after are forbidden — they leave the operator with no actionable surface and force a manual nudge. The post-restart resume contract for step 7 is the canonical case: when the cloudflare-relay turn arrives at `currentStep=7`, the agent's first turn must acknowledge AND immediately render the step-8 prompt (or `anthropic-setup`'s next surface) without an intervening dead-end paragraph. Same rule applies turn-by-turn through step 9. The `assistant-step-advance-deadend` review-detector rule (`platform/ui/app/lib/review-detector/rules.ts`) fires when this contract is violated, so an agent that drifts back to bare prose surfaces a `[review-detector]` alert against itself.
+**Turn-completion contract.** Any onboarding turn that advances `currentStep` (via `onboarding-complete-step`) OR narrates a step transition with phrases like "Moving to step N", "Proceeding to step N", "Step N done" MUST end with one of: a `render-component` call surfacing the next step's UI, OR a `?`-terminated question. Bare prose statements like "Moving to step 9 — operator persona and profile bootstrap." with nothing after are forbidden — they leave the operator with no actionable surface and force a manual nudge. Same rule applies turn-by-turn through step 9. The post-restart resume contract (Task 881) for step 7 is the canonical case: when the operator's "Cloudflare setup completed" message arrives post-restart at `currentStep=7`, the agent's first turn must acknowledge AND immediately render the step-8 prompt (or `anthropic-setup`'s next surface) without an intervening dead-end paragraph.
 
 ## Step 1 — Plugin selection
 
@@ -144,7 +144,7 @@ Then call `render-component` with `name: "cloudflare-setup-form"` and data conta
 
 Wait for the user's submission. The `_componentDone` payload contains the `setup-tunnel.sh` output verbatim. Relay that output to the user — quote any `ACTION REQUIRED` block exactly. When the script exits zero, step-7 completion has already been persisted by the script itself (Task 562) — relay the output and stop. Do not call `onboarding-complete-step` with step 7; the script is the authority for step-7 completion, and any call you make after the script's restart dispatch would race the service restart and almost always lose. If the script failed (the endpoint returned `ok: false, field: "script"`), the form surfaced the error and stayed open — relay the output, cite `plugins/cloudflare/references/reset-guide.md` for recovery, and offer to re-render the form after any manual steps. Do not synthesise alternative recovery commands. If the user skipped (step 7 not reached), call `onboarding-complete-step` with step 7 so the next session resumes at step 8.
 
-**Post-restart resume contract (Task 867).** A successful Cloudflare setup arms a brand-service restart that kills the in-flight admin agent; the operator's "Cloudflare setup completed" relay is queued by the form (write-once filesystem queue) and dispatched server-side as the first turn of the post-restart session via the boot-drain hook in `server/index.ts`. By the time a new admin session opens, `OnboardingState.currentStep` is already 7 (the script's filesystem flag was consumed by `consumeStep7FlagUI` on the way in) AND the queue's relay turn has been persisted as the most-recent user message. From your view as the admin agent, the operator just told you "Cloudflare setup completed (actionId: …)" in a fresh session at currentStep=7. Acknowledge, then proceed to step 8 — do NOT re-ask the Cloudflare question, do NOT re-render the cloudflare-setup-form, do NOT call `onboarding-complete-step` with step 7 (already done). The relay turn is your single source of truth that step 7 finished cleanly; the script's flag-consume is the orthogonal proof that the state machine advanced.
+**Post-restart resume contract (Task 881).** A successful Cloudflare setup arms a brand-service restart that kills the in-flight admin agent; the operator's "Cloudflare setup completed" message is replayed by the chat client itself after the restart cycle completes (`POST /api/admin/sessions/<cid>/resume` re-binds the session via the surviving `__remote_session` cookie, then the client sends the marker as a normal hidden chat POST). By the time you receive that marker, `OnboardingState.currentStep` is already 7 (the script's filesystem flag was consumed by `consumeStep7FlagUI` on the way in). From your view as the admin agent, the operator just told you "Cloudflare setup completed (actionId: …)" at currentStep=7. Acknowledge, then proceed to step 8 — do NOT re-ask the Cloudflare question, do NOT re-render the cloudflare-setup-form, do NOT call `onboarding-complete-step` with step 7 (already done). The marker turn is your single source of truth that step 7 finished cleanly; the script's flag-consume is the orthogonal proof that the state machine advanced.
 
 ## Step 8 — Anthropic API key
 

package/payload/platform/plugins/docs/references/cloudflare.md

@@ -30,9 +30,7 @@ When you submit, the `/api/admin/cloudflare/setup` endpoint runs — in strict o
 - `cloudflared tunnel route dns` for each subdomain hostname. Apex hostnames cannot be routed this way — the script prints an **ACTION REQUIRED** block naming the exact dashboard record to add or edit. Stream log emits `step=route-dns hostname=… tunnel_id=…` before the call and `step=route-dns hostname=… result=ok|apex-skip|error` after; on error the bounded cloudflared stderr (≤400 chars) rides in the same phase line. **The script does not parse cloudflared's stdout** — exit code is the sole decision signal, so all three legitimate cloudflared output shapes (new record, overwrite, idempotent "already configured") are treated as success.
 - `config.yml` and `tunnel.state` written under `${CFG_DIR}`.
 - **Step-7 onboarding completion persisted** — the script writes `${ACCOUNT_DIR}/onboarding/step7-complete` (a JSON marker with the completion timestamp and tunnel ID) before arming the restart. Stream log: `step=onboarding-persist result=ok|error reason=<r>`. The marker is consumed by the next admin session's first state read and advances `OnboardingState.currentStep` to 7. Without this, the service restart below would SIGTERM the admin agent before it could persist step-7 completion, and the next session would re-ask the Cloudflare question you just finished. Both invocation surfaces (the form-driven action and the agent-via-Bash path) declare `ACCOUNT_DIR` explicitly because `systemd-run --user` does not inherit parent env — when ACCOUNT_DIR isn't reaching the script you'll see `result=skipped reason=no-account-dir` in the stream log instead of `result=ok`.
-- **Chat-relay queued for the operator's "Cloudflare setup completed" turn** — when the form's ActionLogPanel reports `code=0`, the form fires `POST /api/admin/cloudflare/relay-completion`. The route enqueues a record at `${ACCOUNT_DIR}/queue/action-completion-relay-<actionId>.json` (write-once via Node's `wx`/O_EXCL flag) BEFORE the brand restart kills the in-flight admin agent. After the restart, the brand service's boot-drain hook ([server/index.ts](../../../../platform/ui/server/index.ts)) consumes the queue once and dispatches a server-driven agent turn via a synthetic one-shot session bound to the queued conversationId; the agent's hoisted user-message persist writes `role=user` BEFORE the SDK invoke so the operator's relay survives even if SIGTERM hits mid-generation. The diagnostic line you grep on the working path is `[action-completion-relay] phase=consumed actionId=<id> conversationId=<cid> ageMs=<n> outcome=injected`. Failure modes are surfaced by the `cloudflare-setup-relay-not-acknowledged` review rule.
-- **Chat-surface restart-pending banner** — the same `admin-chat:await-relay` CustomEvent that registers the relay-poll now also carries `reason: 'cloudflare-setup'` so the chat hook ([useAdminChat.ts](../../../../platform/ui/app/useAdminChat.ts)) renders an inline `"Service restarting after Cloudflare setup — picking back up…"` banner the moment the form fires. Closes the visible-silence window between the form's `Completed · 20s` and the first post-restart agent token. Idempotent on duplicate dispatch. Copy is keyed by `reason` so future restart sources (plugin-install, npm-update) can plug in their own banner without inventing a new chat surface state. Generic fallback `"Service restarting — reconnect will happen automatically."` is used when the dispatch omits `reason`.
-- **Client sessionKey rebind on first post-restart poll** — when the relay-poll observes its first `200` for the captured cid (server-side cookie-bridge has just hydrated `(accountId, userId)` onto the wiped sessionStore entry), the chat hook fires `POST /api/admin/session/rebind` exactly once with `{session_key, lastKnownConversationId}`. The endpoint validates accountId scope via `getConversationOwner(cid).accountId === sessionAccountId` and binds the conversationId to the session via `setConversationIdForSession`. `sendMessage` awaits the in-flight rebind promise before opening the next chat POST, closing the silent-fork race where the operator's next turn would otherwise create a NEW Conversation and the `[admin/conversation-flush] result=missing-userId|writer-failed` line never reached the chat surface. Diagnostic: `grep '\[admin/session/rebind\]' ~/{configDir}/logs/server.log` — expects `result=ok conversationId=<cid8>` once per restart cycle; `result=conflict` means the server holds a different canonical cid (client adopts it).
+- **Post-restart resume contract** — when the form's ActionLogPanel reports `code=0`, the form dispatches the `admin-chat:post-restart-resume` window CustomEvent with `{actionId, message}`. The chat hook ([useAdminChat.ts](../../../../platform/ui/app/useAdminChat.ts)) waits for the brand-service down-then-up cycle on `/api/health`, calls `POST /api/admin/sessions/<cid>/resume?session_key=<sk>` (cookie-bridge-rehydrates the wiped sessionStore via the surviving `__remote_session` cookie and binds the conversation), then sends the captured "Cloudflare setup completed (actionId: <id>)." marker as a normal hidden chat POST that re-invokes the agent. No relay queue, no boot-drain, no banner, no rebind endpoint. Diagnostic: `grep '\[admin-resume\] reason=post-restart' ~/{configDir}/logs/server.log` (expect one line per restart cycle), `grep '\[client-event\] kind=post-restart-resume' ~/{configDir}/logs/server.log` for the operator-visible client trace. See `.docs/web-chat.md` "Post-restart resume contract" for the full client/server contract.
 - `systemctl --user restart ${BRAND}.service` — restarts the platform service so the new tunnel spawns via the service's `ExecStartPre=resume-tunnel.sh`.
 - Post-restart verification — `ps -ef | grep '[c]loudflared'` confirms the connector is alive, then `curl -I https://<hostname>` against each subdomain (up to 60 s per host) confirms a non-530 response.
 

package/payload/platform/plugins/docs/references/troubleshooting.md

@@ -192,25 +192,21 @@ The transient unit was auto-collected by systemd before the client subscribed. R
 
 **Cloudflare-setup auto-relays "completed" but the next chat turn 502s.**
 
-Pre-Task-860, `CloudflareSetupForm` dispatched the post-success chat message immediately on `exit{code:0}`. The relay POST hit the admin server inside the brand-restart bounce window (`~3 s` after `step=service-restart-armed`) and returned `Error: Request failed (502)`. An earlier fix added an `awaitAdminReachable` holdback that polled `/api/admin/version` before dispatch. **earlier platform fixes deleted the holdback** — `/api/admin/version` is on `maxy-edge.service` (earlier platform fixes peer surface) which never restarts, so the probe always returned 200 immediately and never actually waited.
-
-The replacement is a write-once filesystem queue + boot-drain. The form fires `POST /api/admin/cloudflare/relay-completion`, the route enqueues to `${accountDir}/queue/action-completion-relay-<actionId>.json`, and the brand-service boot-drain hook in `server/index.ts` consumes the queue on the next process-init via a synthetic one-shot session that calls `invokeAgent` directly. The agent's user-message persist is hoisted to BEFORE SDK invoke so even if SIGTERM hits mid-generation, the user message survives.
+Earlier platform fixes (relay queue + boot-drain) replaced an even earlier `awaitAdminReachable` holdback that polled the non-restarting edge surface. The current contract is a single client-driven resume: the form dispatches the `admin-chat:post-restart-resume` window CustomEvent on `exit{code:0}`, the chat hook waits for `/api/health` to fail then succeed (down-then-up cycle, `waitForRestartCycle`), calls `POST /api/admin/sessions/<cid>/resume?session_key=<sk>` (cookie-bridge-rehydrates the wiped sessionStore via the surviving `__remote_session` cookie and binds the conversation), then sends the marker as a normal hidden chat POST that re-invokes the agent under the operator's real session. No relay queue, no boot-drain, no banner, no rebind endpoint.
 
 Diagnostic recipe:
 
 ```
-ls ${ACCOUNT_DIR}/queue/ # any *.json present = consumer not running
-grep '\[action-relay-queue\] phase=enqueued' ~/.maxy/logs/server.log | tail
-grep '\[action-completion-relay\] phase=consumed' ~/.maxy/logs/server.log | tail
-grep '\[persist\].* role=user.* Cloudflare setup completed' ~/.maxy/logs/server.log | tail
-grep '\[client-event\] source=cloudflare-setup-form' ~/.maxy/logs/server.log | tail
+grep '\[admin-resume\] reason=post-restart' ~/.maxy/logs/server.log | tail   # /resume server-side
+grep '\[session\] cookie-bridge accountId=' ~/.maxy/logs/server.log | tail   # session re-hydrated
+grep '\[persist\] .* role=user .* Cloudflare setup completed' ~/.maxy/logs/server.log | tail
+grep '\[client-event\] kind=post-restart-resume' ~/.maxy/logs/server.log | tail
 ```
 
 Failure modes:
-- `phase=enqueued` absent: form's POST never landed (check `[client-event]` for the dispatch line).
-- `phase=enqueued` present, `phase=consumed` absent within 60s of the next brand restart: boot-drain hook regressed.
-- Both present, `[persist] role=user` absent: persist hoist regressed (admin-agent.ts).
-- Review-detector rule `cloudflare-setup-relay-not-acknowledged` is the consolidated alarm — fires if any of the above is missing within 60s of `[script:setup-tunnel] step=done`.
+- `[client-event] kind=post-restart-resume phase=start` absent: form's CustomEvent never reached the chat hook (regression in form `onExit` or chat-listener mount).
+- `[client-event] phase=start` present, `[admin-resume] reason=post-restart` absent: `waitForRestartCycle` exhausted its bound (brand never restarted) or `/resume` rejected — check `phase=health-timeout` / `phase=resume-rejected`.
+- All four present except `[persist] role=user … Cloudflare setup completed`: marker chat POST failed — check the chat surface for an inline error or a `phase=resume-error` line.
 
 ---